<HTML>
<HEAD>
<link rel=stylesheet type="text/css" href="styles.css">
<TITLE>Simkin on Symbian</TITLE>
</HEAD>
<BODY>

<H1>
Simkin on Symbian</H1>
<hr>
<p>
<h3>Symbian preprocessor directives</h3>
Since version 2.18 Simkin has been available for Symbian OS - which runs on many popular mobile phones, as well as Psion organizers.
<p>
The porting effort was generously supported by <a target="_blank" href="http://www.symbian.com">Symbian Ltd</a>.
<p>
There are various issues with the support for C++ on Symbian:
<p>
<ol>
<li>Symbian has its own kind of exception called a <b>leave</b> - this may never occur within a C++ class constructor
<li>Symbian uses a special construct called a <b>CleanupStack</b> to keep track of allocated memory in case a leave occurs</li>
<li>C++ Exceptions are not supported</li>
<li>C++ Streams are not supported</li>
<li>Unicode characters are used</li>
</ol>
<p>
Simkin contains preprocessor directives to provide a special version of the library to address these issues:
<ol>
<li><b>__SYMBIAN32__</b><br>if defined, any class constructors which could leave are not available. This directive also enables various functions which make integration with Symbian descriptors easier
<p>
</li>
<li><b>SAVE_POINTER</b>/<b>RELEASE_POINTER</b> <b>SAVE_VARIABLE</b>/<b>RELEASE_VARIABLE</b>
<br>These macros add and remove object pointers, and stack-based values (such as <a href="symbian/api/classskString.html">skString</a> and <a href="symbian/api/classskRValue.html">skRValue</a>) to the Cleanup Stack. For other platforms, these macros do nothing.
<p>
</li>
<li><b>EXCEPTIONS_DEFINED</b><br>if undefined, code using C++ exceptions is disabled. 
<br>An <a href="symbian/api/classskExecutableContext.html">skExecutableContext</a> object is passed to method calls which uses an <a href="symbian/api/classskScriptError.html">skScriptError</a> object to catch any errors that would normally be thrown as a C++ exception.<p>
</li>
<li><b>STREAMS_ENABLED</b><br>if undefined this disables all the code within Simkin which relies on C++ streams<p>
</li>
<li><b>UNICODE_STRINGS</b><br>if defined, this enables code which uses unicode wide character strings rather than standard 8-bit characters
</ol>
<p>
<h3>Building Simkin/C++ for Symbian</h3>
<p>
Simkin should be built as a static DLL on the Symbian platform.  You can do this using the <code>bld.inf</code>.
<p>
<h4>XML version</h4>
The <code>SimkinSym_XML.mmp</code> project builds generates a DLL called <code>SimkinXML.dll</code> and a library called <code>SimkinXML.lib</code>. 
The XML support is provided by a special version of the <a href="http://expat.sourceforge.net" target="_blank">Expat XML parser</a>, and the <a href="CppClasses.html#SimkinDOM">Simkin DOM classes</a>.
<p>You can download the special version of Expat <a href="http://www.simkin.co.uk/download/Expat-1.95.5-ce-sym.zip">from the Simkin site</a>. You will need to use the <code>bld.inf</code> file in the <code>Symbian</code> subdirectory to build <code>expat.dll</code> and <code>expat.lib</code>.
<p>
We have provided two specific examples for the XML version:
<ol>
<li><b>ScriptLoaderXML</b> (directory <code>scriptloader_xml_sym</code>) - this is a command line application which loads a script called "test.xml" from the root of the C: drive.</li>
<li><b>SimkinDemoXML</b> (directory <code>demo_xml_sym</code>)- this GUI app shows a simple calculator whose layout and behaviour is defined in a script called "SimkinDemo.xml". The application uses the Quartz SDK, but could be modified to use earlier versions. 
</li>
</ol>
<h4>TreeNode version</h4>
The <code>SimkinSym.mmp</code> project builds generates a DLL called <code>Simkin.dll</code> and a library called <code>Simkin.lib</code>. This includes the <code>skTreeNode</code> classes for storing scripts. 
<p>
We have provided two specific examples for the Treenode version:
<ol>
<li><b>ScriptLoader</b> (directory <code>scriptloader_sym</code>) - this is a command line application which loads a script called "test.dat" from the root of the C: drive.</li>
<li><b>SimkinDemo</b> (directory <code>demo_sym</code>)- this GUI app shows a simple calculator whose layout and behaviour is defined in a script called "SimkinDemo.dat". The application uses the Quartz SDK, but could be modified to use earlier versions. 
</li>
</ol>
</body>
</html>
